【社内資料公開】運用手順書を作る時のポイントについて書いてみた

植木和樹

2016.06.30

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

はじめに

こんにちは植木和樹＠上越妙高オフィスです。本日は私がここ10年くらい意識している運用手順書を書くときのポイントについてまとめてみました。

対象読者

開発・構築したシステムを別の人に引き継ぐ予定のある人
他の人が作ったシステムを引き継ぐ担当の人
半年後の自分でも分かる手順書の書き方に困っている人

（この記事を読むのにかかる時間の目安：5分）

1. ドキュメントの冒頭に書くこと

まず個々の詳細手順の前に、ドキュメント自体について記載してもらいたいことです。

1.1. ドキュメントに書かれていることを3行で書く

ドキュメントの最初には、このドキュメントに何が書かれているのかを100文字くらいで書いておくと良いでしょう。

システムが増えれば増えるほど手順書も増えていくものです。見つけたドキュメントに自分の期待するものが書かれているのか、冒頭数行でわかるようになっているとうれしいです。

1.2. 対象者/必要スキルを定める

ドキュメントの対象者を書きましょう。特に必要スキルについては簡単でも良いので書いておくと良いです。

AWSマネージメントコンソールでEC2の操作ができること
ansible-playbookを使った構成変更ができること

開発者（ドキュメント作成者）の立場からすると、作業する人のスキルがどの程度なのか分からないと、どこまで詳細に書いたらいいものか悩んでしまいます。そこで「最低限この辺のスキルができる人を対象にしてますよー」というのを示しておくと手順も必要以上に冗長にならず良いです。

クラスメソッドのオペレーションチームでは標準スキルセットを定めてます（社内試験がある）ので、知りたい人はお声かけください。

1.3. 作業環境について書く

いきなり「管理画面にログインして〜」と書かれても困ってしまいます。操作環境について書いておきましょう。

AWSアカウントID
管理画面URL
Beanstalk アプリケーション名
ログインユーザー/パスワード（もちろん作業者個人ごとに発行するのが望ましいですよ！えぇ）

1.4. 構成図を貼り付ける

見知らぬシステムを任されるのは怖いものです。システム構成図が1枚あるだけで「なるほど、こういう構成になってるのか」と安心できます。

典型的な構成としては以下のものでしょうか。EC2あたりは要素の横に、動いているアプリケーション(ApacheとかTomcatとか)が書いてあると尚良いです。

ELB
EC2 (AutoScaling? Opsworks? Beanstalk?)
ElastiCache(memcached or redis)
RDS (MySQL? PostgreSQL? Oracle? SQLServer?)

2. 個別作業手順ごとに書くこと

次に個々の詳細手順に書いておいてもらいたいことです。

2.1. 作業にかかる目安時間を書く

作業にかかる目安時間があるとうれしいです。30分くらいで終わる作業なのか、4時間かかる作業なのか。

目安時間がわかると作業日程調整時の参考になりますので。

2.2. いつ、それをするのか？を書く

いきなり「サーバーリブート手順」とだけあるのではなく、どんな時にその手順を実施するのか書いておいてください。ストーリーがあると理解しやすくなります。

障害発生時
作業依頼がきた時（不定期）
日次/週次/月次

2.3. 作業手順の書き方

実際の作業手順は好きに書いてもらって良いです。最終的にはレビューして不足は修正していきますので。

前述した「想定するスキルレベル」の人が分かるように書くようにしましょう。オペレーションチーム宛なら「マネージメントコンソールでEC2をStopしてください」でも通じます（権限取得や操作手順はチーム内で標準化/共有されてますので）

なお経験的にいうと、引き継いだ手順書がその後修正なしで運用されるケースは滅多にありません。分かりづらい言い回しが修正されたり、作業者視点でのメモや注意箇所などが書き込まれたりしてどんどんブラッシュアップされていくものです。

最初から完璧を求め過ぎると「ドキュメント書きたくない → 書かない → 属人化」の悪循環にはまってしまいます。まずは作業メモレベルで良いのです。

2.4. 確認手順を書く

作業手順だけが書かれていて、確認手順が記載されていないことが多いです。作業が正しくできているのか確認する手順も記載してください。

ELBのステータスがInServiceになっていること
BeanstalkのステータスがGreenになっていること
作成したユーザーでXXXXという操作ができること
ブラウザで XXXXX へアクセスして画面が表示できること

3. エスカレーション先を書く

不幸なことに手順書通りに進めてもうまくいかないことがあります。また手順書に記載されていない作業が求められることもあるでしょう。特に想定外の障害が発生した場合には開発（保守）チームにエスカレーションすることになります。

ただ「想定外のことがあったら開発チームに緊急エスカレーションしてください」だけではどうしたらいいか分かりません。

3.1. 連絡手段を書く

エスカレーションの手段を書いておきましょう。

メーリングリスト
Backlog
Chatwork

3.2. 宛先を書く

開発チームの宛先を書いておきましょう。

メールアドレス
Backlogのプロジェクト名とアサインする担当者
Chatworkの部屋（メンションする人がいれば担当者名）

おまけ：個人的な趣向

これ以降はとても個人的な意見です。

版数はつける？どうつける？

版数はつけてほしいです。手順書がファイル（WordやExcel(!)）に記載されているなら必須です。手順書がWikiなどオンラインで参照するなら、常に最新版であることが保証されるのでなくてもいいです。（たまに印刷してる人いますけど）

版数はv1.0とかでなく、更新日付（v20160629とか）が一番わかりやすい。

ドキュメントの分割

細かくドキュメントを分割されるより、すべての手順が1ページにまとまっててくれた方がうれしいです。そのシステムに関する手順が見たければ、とにかくそのページ（ファイル）を開けば良いからです。

ページを開いた後に、目次やページ内検索で探すのが一番ヒット率が高い気がします。

細かくページやファイルが分割されている場合は、分かりやすい構成になっていないと探したい情報に辿りつけない事が多いです。（で「◯◯の手順のドキュメントありましたっけ？」って開発担当者に聞くことになる）

それと一つの作業をするのに複数のページを行き来しないといけなかったりするので使い勝手が悪いこともしばしばです。

目次で作業ステップが分かるようにする

目次を読むだけで、どんな作業をするのか分かるようになっているとうれしいです。

例えば障害のあったEC2を復旧させる手順について書く場合にはこんな感じでしょうか。

1. Webサーバーステータス障害時の復旧手順（作業目安： 10分）
1.1. 障害の発生しているサーバーのインスタンスIDを確認する
1.2. サーバーをTerminateする
1.3. AutoScalingで新しいサーバーが起動するまで待つ
1.4. ELBでInServiceになっていることを確認する

ドキュメントの置き場所

開発者はシステム単位で仕事をするため下記のようなディレクトリ構成にすることが多いですよね。

/顧客管理システム
　/ドキュメント
　　/仕様書
　　/手順書 （見たいのはこっち）

しかしオペレーション担当は複数のシステムを横断的にみているため、階層の親子関係が逆になってた方が使いやすいのです。

/ドキュメント
　/手順書
　　/顧客管理システム
　　/売上管理システム

そのため現場では自分たちが参照しやすいようにファイルをコピーしてしまい、版数の違う手順書が各所に散乱するという状態になりがちです。

最近はページにタグ付けできるWikiが使えますので、ドキュメントはWikiにまとめて「手順書」タグをつけるとか、手順書一覧ページからリンクを貼るのがベストだと思ってます。もしくはBacklogやRedmineのようにプロジェクト毎にファイル置き場があって、ドキュメントはそこにまとめる（で、ポインタだけ集中管理する）、でもいいと思います。